HSP Docs Library (HDL) は、HSP のドキュメントをまとめて 検索・閲覧 するためのブラウザです。
hs ヘルプファイル、txt/HTML ドキュメント、サンプルスクリプトを一括して検索したり、相互参照したりすることができます。
ライブラリのファイルは、次のディレクトリから検索されます。
| ディレクトリ | 検索されるファイル |
|---|---|
| doclib | *.hs *.txt *.htm *.html *.hsp |
| hsphelp | *.hs |
| sample | *.hsp |
| common | *.as *.hsp (ドキュメント付けされたヘッダファイル) |
HDL のライブラリに新たなドキュメントを追加する場合は、ファイルを doclib ディレクトリに配置してください。
プラグインやモジュールごとに、doclib ディレクトリ下にカテゴリ ディレクトリを作成し、 その中に関連ドキュメント (hs, hsp サンプル, txt, HTML 文書やそれで使われる画像、スタイルシートなど) をまとめると、 ファイル数が多くなっても管理しやすくなります。
ドキュメントの文字コードは、Shift_JIS と UTF-8 がサポートされています。このドキュメントは、UTF-8 で保存されています。
HDL では、読み込まれたファイルの集合を ライブラリ と呼びます。ライブラリは コマンドヘルプ, ドキュメント, サンプル という 3 つの セクション に分かれます。 それぞれのセクションは、さらに カテゴリ に細分化されます。カテゴリの下に、コンテンツ本体である ページ があります。
.hs ヘルプファイルの内容は、コマンドヘルプ セクションに振り分けられます。コマンドヘルプセクション内のカテゴリは、使用プラグインごとに分けられます。
.txt .htm .html ファイルは、ドキュメント セクションに振り分けられます。
.hsp ファイルは、サンプル セクションに振り分けられます。 ドキュメントセクションとサンプルセクション内のカテゴリは、実際にファイルが置かれているディレクトリ名で分けられます。サブディレクトリに属していないファイルは、「デフォルト」カテゴリに区分されます。
common ディレクトリにドキュメント付けされたヘッダファイル (.as .hsp) がある場合は、その内容はコマンドヘルプセクションに区分されます。
HDL は、コマンドヘルプマニュアル用のヘルプファイルとして、HSP 独自の hs 形式のヘルプファイルをサポートしています。
hs ファイルの書式については、HS_BIBLE.txt を参照してください。
HDL には、hs ファイルの %inst フィールド内で "html{" と書いた行から "}html" と書いた行までの間を、ダイレクトに HTML として表示する「インライン HTML」という機能があります。
これは hs ファイルとしての仕様ではなく HDL の表示上の仕様で、hs ファイルで HTML の表現を一部利用することができます。
; hs ファイル書式例
%index
stickf
キー入力情報取得
%inst
stickf 関数は、以下のような複数のキーの状態の OR 値を返します。
html{
<table border=1>
<tr><th>値</th><th>キー</th></tr>
<tr><td>1</td><td>カーソルキー左(←)</td></tr>
<tr><td>2</td><td>カーソルキー上(↑)</td></tr>
<tr><td>4</td><td>カーソルキー右(→)</td></tr>
<tr><td>8</td><td>カーソルキー下(↓)</td></tr>
<tr><td>16</td><td>スペースキー</td></tr>
<tr><td>32</td><td>Enterキー</td></tr>
<tr><td>64</td><td>Ctrlキー</td></tr>
<tr><td>128</td><td>ESCキー</td></tr>
</table>
}html
インライン HTML の区間について、中の HTML の書式は HDL によってチェックされません。 誤った HTML が記述されているとページ全体のレイアウトが崩れたりする可能性もありますので、hs データの配布などを行う場合は十分にチェックを行ってください。 また、情報の意味づけに関係しない、装飾的な目的での HTML の使用は避けるようにしてください。
インライン HTML ではアクティブスクリプト (javascript 等) の記述を行わないでください。 スクリプトの実行に関するいくつかのキーワードは、使用を制限されています。インライン HTML で使用した要素のスタイルは、外部 CSS の影響を受ける場合があります。
HDL の出力ページのドキュメントタイプは、HTML 5 です。
ドキュメントやサンプルスクリプト作成の際には、下記の点に留意いただけますと、視認性、検索性が向上します。
HTML ファイルの title タグの内容は、ドキュメントのタイトルとして認識されます。 タイトルは、ドキュメントの中身が何であるか分かりやすいものにしてください。
サンプルスクリプトや txt ファイルは、ファイル名がそのタイトルとなります。 "test1.hsp" のようなファイル名は、中身が何であるか推測できないため、避けるべきです。
これは、サンプルやドキュメントのディレクトリ名 (= カテゴリ名) にも言えます。
hs ファイルの本文を固定字数で改行すると、 ビューアーのウィンドウサイズやフォントサイズによっては読みづらくなる場合があります。 パラグラフの折り返しは、ビューアーのウィンドウ幅に任せるようにしてください。
HTML ドキュメントの横幅は絶対値に固定しないで、ブラウザのウィンドウ幅を小さくしていても読めるようにしてください。
HDL の最新バージョンは、s.programe net http://spn.php.xdomain.jp/ で公開されています。